#!/bin/bash
###############################################################################
#       脚本名称: utils_jq.sh
#       功能描述: JSON数据格式处理工具模块，提供纯粹的JSON数据操作功能。
#       作者: 林再来
#       日期: 2025-10-15
#       版本: 1.0
#       功能:
#           1、JSON文件读取、写入、删除操作
#           2、JSON文件格式验证
#           3、JSON文件合并和格式化功能
#           4、JSON数组和对象操作功能
#           5、支持jq原生查询和过滤功能
#       依赖(插件/命令):
#           1、jq命令行工具
#           2、curl(用于下载jq工具，可选)
###############################################################################

# 防止重复加载
if [[ -n "${utils_jq_sh_loaded:-}" ]]; then
    return 0
fi
readonly utils_jq_sh_loaded=1

# 注意：不使用严格模式，避免影响交互式 shell

# 获取脚本目录和项目根目录（如果尚未定义）
if [[ -z "${script_dir:-}" ]]; then
    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    readonly script_dir
fi

if [[ -z "${project_root:-}" ]]; then
    project_root="$(cd "${script_dir}/../.." && pwd)"
    readonly project_root
fi

###############################################################################
# 全局常量
###############################################################################

readonly UTILS_JQ_DEFAULT_VERSION="v1.6"
readonly UTILS_JQ_PACKAGES_DIR="$project_root/packages/jq"

###############################################################################
# 全局变量
###############################################################################

utils_jq_binary="${utils_jq_binary:-}"
utils_jq_version="${utils_jq_version:-$UTILS_JQ_DEFAULT_VERSION}"

###############################################################################
# 工具初始化
###############################################################################

# 函数: 初始化jq工具
# 参数: 无
# 返回: 0-成功, 1-失败
# 说明: 自动检测系统jq或使用项目内置jq
function utils_jq_init() {
    log_debug "utils_jq" "初始化jq工具"
    
    # 如果utils_jq_binary已设置，检查是否可用
    if [[ -n "$utils_jq_binary" ]] && command -v "$utils_jq_binary" >/dev/null 2>&1; then
        log_debug "utils_jq" "使用已设置的jq: $utils_jq_binary"
        return 0
    fi
    
    # 检查系统是否已安装jq
    if command -v jq >/dev/null 2>&1; then
        utils_jq_binary="jq"
        log_info "utils_jq" "使用系统jq: $(which jq)"
        return 0
    fi
    
    # 检查项目内置jq
    local arch=""
    case "$(uname -m)" in
        x86_64|amd64) 
            arch="amd64" 
            ;;
        aarch64|arm64) 
            arch="arm64" 
            ;;
        *) 
            log_warn "utils_jq" "未知架构: $(uname -m)，尝试使用amd64"
            arch="amd64" 
            ;;
    esac
    
    local jq_path="$UTILS_JQ_PACKAGES_DIR/$utils_jq_version/$arch/jq_linux_$utils_jq_version"
    
    if [[ -f "$jq_path" ]]; then
        chmod +x "$jq_path" 2>/dev/null || {
            log_error "utils_jq" "错误: 无法设置jq执行权限: $jq_path"
            return 1
        }
        
        if [[ -x "$jq_path" ]]; then
            utils_jq_binary="$jq_path"
            log_info "utils_jq" "使用内置jq: $jq_path"
            return 0
        else
            log_error "utils_jq" "错误: jq文件无执行权限: $jq_path"
            return 1
        fi
    else
        log_error "utils_jq" "错误: 未找到内置jq: $jq_path"
    fi
    
    log_error "utils_jq" "错误: 未找到可用的jq工具"
    return 1
}

###############################################################################
# 基础数据操作
###############################################################################

# 函数: 验证JSON文件格式
# 参数: $1 - JSON文件路径
# 返回: 0-格式正确, 1-格式错误
function utils_jq_validate() {
    local json_file="$1"
    
    if [[ -z "$json_file" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "验证JSON文件格式: $json_file"
    
    if "$utils_jq_binary" '.' "$json_file" >/dev/null 2>&1; then
        log_debug "utils_jq" "JSON文件格式正确: $json_file"
        return 0
    else
        log_error "utils_jq" "错误: JSON文件格式错误: $json_file"
        return 1
    fi
}

# 函数: 读取JSON文件中的值
# 参数: $1 - JSON文件路径, $2 - 要读取的键路径
# 返回: 0-成功, 1-失败
# 输出: 读取的值(stdout)
function utils_jq_read() {
    local json_file="$1"
    local key="$2"
    
    if [[ -z "$json_file" ]] || [[ -z "$key" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径和键"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "读取JSON值: $json_file -> $key"
    
    # jq查询表达式，使用-r输出原始字符串
    local result
    if result=$("$utils_jq_binary" -r "$key" "$json_file" 2>/dev/null); then
        # 如果结果是 null，返回空字符串
        if [[ "$result" = "null" ]]; then
            echo ""
        else
            echo "$result"
        fi
        return 0
    else
        log_error "utils_jq" "错误: 读取JSON值失败: $json_file -> $key"
        return 1
    fi
}

# 函数: 写入值到JSON文件
# 参数: $1 - JSON文件路径, $2 - 要写入的键路径, $3 - 要写入的值, $4 - 值类型(可选: string/number/boolean/array/object)
# 返回: 0-成功, 1-失败
function utils_jq_write() {
    local json_file="$1"
    local key="$2"
    local value="$3"
    local value_type="${4:-string}"
    
    if [[ -z "$json_file" ]] || [[ -z "$key" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径和键"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    # 如果文件不存在，创建空的JSON文件
    if [[ ! -f "$json_file" ]]; then
        log_info "utils_jq" "JSON文件不存在，创建新文件: $json_file"
        echo "{}" > "$json_file"
    fi
    
    log_debug "utils_jq" "写入JSON值: $json_file -> $key = $value ($value_type)"
    
    # 根据值类型构建jq表达式
    local jq_expression
    case "$value_type" in
        "number")
            jq_expression="$key = $value"
            ;;
        "boolean")
            jq_expression="$key = $value"
            ;;
        "array"|"object")
            jq_expression="$key = $value"
            ;;
        "string"|*)
            jq_expression="$key = \"$value\""
            ;;
    esac
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 执行写入操作
    if "$utils_jq_binary" "$jq_expression" "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        # 验证结果
        if utils_jq_validate "${json_file}.tmp"; then
            mv "${json_file}.tmp" "$json_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON值写入成功"
            return 0
        else
            log_error "utils_jq" "错误: 写入后JSON文件格式错误，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON值写入失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

# 函数: 删除JSON文件中的键
# 参数: $1 - JSON文件路径, $2 - 要删除的键路径
# 返回: 0-成功, 1-失败
function utils_jq_delete() {
    local json_file="$1"
    local key="$2"
    
    if [[ -z "$json_file" ]] || [[ -z "$key" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径和键"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "删除JSON键: $json_file -> $key"
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 执行删除操作，使用 del() 函数
    if "$utils_jq_binary" "del($key)" "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        # 验证结果
        if utils_jq_validate "${json_file}.tmp"; then
            mv "${json_file}.tmp" "$json_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON键删除成功"
            return 0
        else
            log_error "utils_jq" "错误: 删除后JSON文件格式错误，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON键删除失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

###############################################################################
# 文件操作
###############################################################################

# 函数: 合并JSON文件
# 参数: $1 - 目标文件, $2 - 源文件, $3 - 合并模式(可选: merge/overwrite)
# 返回: 0-成功, 1-失败
# 说明: merge模式递归合并，overwrite模式完全覆盖
function utils_jq_merge() {
    local target_file="$1"
    local source_file="$2"
    local merge_mode="${3:-merge}"
    
    if [[ -z "$target_file" ]] || [[ -z "$source_file" ]]; then
        log_error "utils_jq" "错误: 缺少参数: 目标文件和源文件路径"
        return 1
    fi
    
    if [[ ! -f "$source_file" ]]; then
        log_error "utils_jq" "错误: 源文件不存在: $source_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    # 如果目标文件不存在，直接复制源文件
    if [[ ! -f "$target_file" ]]; then
        log_info "utils_jq" "目标文件不存在，复制源文件: $target_file"
        cp "$source_file" "$target_file"
        return $?
    fi
    
    log_debug "utils_jq" "合并JSON文件: $source_file -> $target_file (模式: $merge_mode)"
    
    # 备份目标文件
    local backup_file="${target_file}.bak.$(date +%s)"
    cp "$target_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 根据合并模式执行操作
    local merge_expression
    case "$merge_mode" in
        "overwrite")
            merge_expression='$source[0] * .'
            ;;
        "merge"|*)
            merge_expression='. * $source[0]'
            ;;
    esac
    
    # 执行合并操作
    if "$utils_jq_binary" --slurpfile source "$source_file" "$merge_expression" "$target_file" > "${target_file}.tmp" 2>/dev/null; then
        # 验证结果
        if utils_jq_validate "${target_file}.tmp"; then
            mv "${target_file}.tmp" "$target_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON文件合并成功"
            return 0
        else
            log_error "utils_jq" "错误: 合并后JSON文件格式错误，恢复备份"
            rm -f "${target_file}.tmp"
            mv "$backup_file" "$target_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON文件合并失败，恢复备份"
        rm -f "${target_file}.tmp"
        mv "$backup_file" "$target_file"
        return 1
    fi
}

# 函数: 列出JSON文件中的所有键
# 参数: $1 - JSON文件路径, $2 - 父键路径(可选)
# 返回: 0-成功, 1-失败
# 输出: 键列表(stdout)
function utils_jq_list_keys() {
    local json_file="$1"
    local parent_key="${2:-}"
    
    if [[ -z "$json_file" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "列出JSON键: $json_file"
    
    local expression
    if [[ -n "$parent_key" ]]; then
        expression="$parent_key | keys | .[]"
    else
        expression="keys | .[]"
    fi
    
    if "$utils_jq_binary" -r "$expression" "$json_file" 2>/dev/null; then
        return 0
    else
        log_error "utils_jq" "错误: 列出JSON键失败: $json_file"
        return 1
    fi
}

# 函数: 格式化JSON文件
# 参数: $1 - JSON文件路径, $2 - 缩进空格数(可选，默认2)
# 返回: 0-成功, 1-失败
function utils_jq_format() {
    local json_file="$1"
    local indent="${2:-2}"
    
    if [[ -z "$json_file" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "格式化JSON文件: $json_file (缩进: $indent)"
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 执行格式化，使用 --indent 参数
    if "$utils_jq_binary" --indent "$indent" '.' "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        if mv "${json_file}.tmp" "$json_file"; then
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON文件格式化成功"
            return 0
        else
            log_error "utils_jq" "错误: 无法保存格式化结果，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON文件格式化失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

###############################################################################
# JSON特有功能
###############################################################################

# 函数: 向JSON数组追加元素
# 参数: $1 - JSON文件路径, $2 - 数组路径, $3 - 要追加的值
# 返回: 0-成功, 1-失败
function utils_jq_array_append() {
    local json_file="$1"
    local array_path="$2"
    local value="$3"
    
    if [[ -z "$json_file" ]] || [[ -z "$array_path" ]] || [[ -z "$value" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径、数组路径和值"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "向JSON数组追加元素: $json_file -> $array_path += $value"
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 构建jq表达式：数组路径 += [值]
    local jq_expression="$array_path += [\"$value\"]"
    
    # 执行追加操作
    if "$utils_jq_binary" "$jq_expression" "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        if utils_jq_validate "${json_file}.tmp"; then
            mv "${json_file}.tmp" "$json_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON数组元素追加成功"
            return 0
        else
            log_error "utils_jq" "错误: 追加后JSON文件格式错误，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON数组元素追加失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

# 函数: 从JSON数组删除元素
# 参数: $1 - JSON文件路径, $2 - 数组路径, $3 - 要删除的索引或值
# 返回: 0-成功, 1-失败
function utils_jq_array_remove() {
    local json_file="$1"
    local array_path="$2"
    local index_or_value="$3"
    
    if [[ -z "$json_file" ]] || [[ -z "$array_path" ]] || [[ -z "$index_or_value" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径、数组路径和索引/值"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "从JSON数组删除元素: $json_file -> $array_path -= $index_or_value"
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 判断是索引还是值
    local jq_expression
    if [[ "$index_or_value" =~ ^[0-9]+$ ]]; then
        # 数字，作为索引删除
        jq_expression="del($array_path[$index_or_value])"
    else
        # 字符串，作为值删除
        jq_expression="$array_path -= [\"$index_or_value\"]"
    fi
    
    # 执行删除操作
    if "$utils_jq_binary" "$jq_expression" "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        if utils_jq_validate "${json_file}.tmp"; then
            mv "${json_file}.tmp" "$json_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON数组元素删除成功"
            return 0
        else
            log_error "utils_jq" "错误: 删除后JSON文件格式错误，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON数组元素删除失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

# 函数: 合并JSON对象
# 参数: $1 - JSON文件路径, $2 - 目标对象路径, $3 - 要合并的JSON对象字符串
# 返回: 0-成功, 1-失败
function utils_jq_object_merge() {
    local json_file="$1"
    local object_path="$2"
    local merge_object="$3"
    
    if [[ -z "$json_file" ]] || [[ -z "$object_path" ]] || [[ -z "$merge_object" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径、对象路径和合并对象"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "合并JSON对象: $json_file -> $object_path"
    
    # 备份原文件
    local backup_file="${json_file}.bak.$(date +%s)"
    cp "$json_file" "$backup_file" || {
        log_error "utils_jq" "错误: 无法创建备份文件: $backup_file"
        return 1
    }
    
    # 构建jq表达式：对象路径 *= 合并对象
    local jq_expression="$object_path *= $merge_object"
    
    # 执行合并操作
    if "$utils_jq_binary" "$jq_expression" "$json_file" > "${json_file}.tmp" 2>/dev/null; then
        if utils_jq_validate "${json_file}.tmp"; then
            mv "${json_file}.tmp" "$json_file"
            rm -f "$backup_file"
            log_debug "utils_jq" "JSON对象合并成功"
            return 0
        else
            log_error "utils_jq" "错误: 合并后JSON文件格式错误，恢复备份"
            rm -f "${json_file}.tmp"
            mv "$backup_file" "$json_file"
            return 1
        fi
    else
        log_error "utils_jq" "错误: JSON对象合并失败，恢复备份"
        rm -f "${json_file}.tmp"
        mv "$backup_file" "$json_file"
        return 1
    fi
}

###############################################################################
# 高级查询
###############################################################################

# 函数: 执行jq查询表达式
# 参数: $1 - JSON文件路径, $2 - jq查询表达式
# 返回: 0-成功, 1-失败
# 输出: 查询结果(stdout)
# 说明: 支持jq的所有原生查询功能
function utils_jq_query() {
    local json_file="$1"
    local query="$2"
    
    if [[ -z "$json_file" ]] || [[ -z "$query" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径和查询表达式"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "执行JSON查询: $json_file -> $query"
    
    # 执行查询
    if "$utils_jq_binary" -r "$query" "$json_file" 2>/dev/null; then
        return 0
    else
        log_error "utils_jq" "错误: JSON查询失败: $query"
        return 1
    fi
}

# 函数: 执行jq过滤表达式
# 参数: $1 - JSON文件路径, $2 - jq过滤表达式
# 返回: 0-成功, 1-失败
# 输出: 过滤结果(stdout)
function utils_jq_filter() {
    local json_file="$1"
    local filter="$2"
    
    if [[ -z "$json_file" ]] || [[ -z "$filter" ]]; then
        log_error "utils_jq" "错误: 缺少参数: JSON文件路径和过滤表达式"
        return 1
    fi
    
    if [[ ! -f "$json_file" ]]; then
        log_error "utils_jq" "错误: JSON文件不存在: $json_file"
        return 1
    fi
    
    # 确保jq工具可用
    if ! utils_jq_init; then
        return 1
    fi
    
    log_debug "utils_jq" "执行JSON过滤: $json_file -> $filter"
    
    # 执行过滤
    if "$utils_jq_binary" "$filter" "$json_file" 2>/dev/null; then
        return 0
    else
        log_error "utils_jq" "错误: JSON过滤失败: $filter"
        return 1
    fi
}

###############################################################################
# 帮助函数
###############################################################################

# 函数: 显示帮助信息
function utils_jq_help() {
    cat << 'EOF'
JSON数据处理工具 (utils_jq.sh) - 使用说明

功能函数：
  utils_jq_init                              - 初始化jq工具
  utils_jq_validate <json_file>              - 验证JSON文件格式
  utils_jq_read <json_file> <key>            - 读取JSON值
  utils_jq_write <json_file> <key> <value> [type] - 写入JSON值
  utils_jq_delete <json_file> <key>          - 删除JSON键
  utils_jq_merge <target> <source> [mode]    - 合并JSON文件
  utils_jq_list_keys <json_file> [parent]    - 列出所有键
  utils_jq_format <json_file> [indent]       - 格式化JSON文件
  
JSON特有功能：
  utils_jq_array_append <file> <path> <value>     - 向数组追加元素
  utils_jq_array_remove <file> <path> <index>     - 从数组删除元素
  utils_jq_object_merge <file> <path> <object>    - 合并JSON对象
  utils_jq_query <file> <expression>              - 执行jq查询
  utils_jq_filter <file> <expression>             - 执行jq过滤

参数说明：
  json_file  - JSON文件路径
  key        - 键路径，如：.app.name, .database.port
  value      - 要设置的值
  type       - 值类型：string(默认)|number|boolean|array|object
  mode       - 合并模式：merge(默认)|overwrite
  indent     - 缩进空格数（默认：2）
  expression - jq查询或过滤表达式

使用示例：
  # 基本操作
  utils_jq_read config.json ".app.name"
  utils_jq_write config.json ".app.port" "8080" "number"
  utils_jq_delete config.json ".database.password"
  
  # 数组操作
  utils_jq_array_append config.json ".servers" "192.168.1.100"
  utils_jq_array_remove config.json ".servers" 0
  
  # 对象操作
  utils_jq_object_merge config.json ".database" '{"host":"localhost","port":3306}'
  
  # 查询和过滤
  utils_jq_query config.json '.servers[] | select(.active == true)'
  utils_jq_filter config.json '.users | map(select(.age > 18))'

注意事项：
  1. 本模块为纯数据处理工具，不包含业务逻辑
  2. 配置管理特定功能请使用 config/json.sh
  3. 所有写入操作都会自动创建备份文件
  4. 支持jq v1.6的所有查询语法

EOF
}

###############################################################################
# 简单日志函数（如果外部日志模块不可用）
###############################################################################

if ! command -v log_debug >/dev/null 2>&1; then
    function log_debug() { 
        local module="${1:-}"
        shift
        echo "[DEBUG] [$module] $*" >&2
    }
fi

if ! command -v log_info >/dev/null 2>&1; then
    function log_info() {
        local module="${1:-}"
        shift
        echo "[INFO]  [$module] $*" >&2
    }
fi

if ! command -v log_warn >/dev/null 2>&1; then
    function log_warn() {
        local module="${1:-}"
        shift
        echo "[WARN]  [$module] $*" >&2
    }
fi

if ! command -v log_error >/dev/null 2>&1; then
    function log_error() {
        local module="${1:-}"
        shift
        echo "[ERROR] [$module] $*" >&2
    }
fi
